/**
 * @file    using.h
 * @brief   Documentation: how to use WOSH Framework and its applications.
 ****************************************************************************
 * @author  Alessandro Polo
 * @version $Id: using.h 2378 2010-04-28 22:14:27Z alex $
 ****************************************************************************/
/* Copyright (c) 2007-2010, WOSH - Wide Open Smart Home 
 * by Alessandro Polo - OpenSmartHome.com
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the OpenSmartHome.com WOSH nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY Alessandro Polo ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL Alessandro Polo BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ****************************************************************************/

/*! \page page_using Using WOSH
 *
 * This page explains how to use WOSH in the real world.
 *
 * \section page_using_toc Table of Contents:
 *
 *  - \ref page_using_overview
 *
 *  - \ref page_using_environment
 *  - \ref page_using_shell
 *  - \ref page_using_multimedia
 *  - \ref page_using_communication
 *  - \ref page_using_devices
 *  - \ref page_using_building
 *  - \ref page_using_automations
 *  - \ref page_using_networking
 *
 * See also \ref page_config and \ref page_run
 *
 * @todo [..]
 * \warning This page is \b out-of-date and still \c transitional from WOSH 0.6.030 [ \b byron ] to WOSH 0.8.499 [ \b icarus ].
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_using_overview Overview
 *
 * WOSH is actually used 24/7 by its creator, Alessandro Polo, in order to automate his home.
 * Usually following services and devices are running on the home gateway (server):
 *
 *  - Discovery [wosh::services::DiscoveryUdpBundle]
 *  - Building Manager [wosh::services::BuildingManagerBundle]
 *  - Task Manager [wosh::services::TaskManagerBundle]
 *  - Communication Manager [wosh::services::CommunicationManagerBundle]
 *  - System Services [wosh::services::SystemServicesBundle]
 *  - Butler [wosh::services::ButlerBundle]
 *  - Big Brother [wosh::services::BigBrotherBundle]
 *  - Festival [wosh::services::FestivalBundle]
 *  - Heyu [wosh::services::HeyuBundle]
 *  - Player GStreamer and Phonon [wosh::devices::PlayerGStreamerBundle, wosh::devices::PlayerPhononBundle]
 *  - Jabber Bot [wosh::devices::JabberGlooxBundle]
 *  - Modem Dsl [wosh::devices::ModemDslBundle]
 *  - VGetty Answering Machine [wosh::devices::VGettyAMBundle]
 *
 * Moreover \ref page_applications_woshshop "WOSH WorkShop" and/or
 * \ref page_applications_woshremote "WOSH Remote" runs on my lap/workstation.
 *
 * One more \ref page_applications_woshsrv "WOSH Server" runs on my other Linux box
 * and a \ref page_applications_woshcesrv "WOSH CE Server" lives on my Samsung
 * smartphone which is USB connected with the Linux box.
 *
 * Soon, \ref page_applications_woshkiosk "WOSH KiosK" will run on a new ATX board
 * mouted in-wall.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_using_environment (My) Environment
 *
 * The Residential gateway is an x86 (server) PC, running Debian Etch, online 24/7.
 *
 * There are also some devices in the rack:
 *  - Ethernet interfaces 1Gbps [3]
 *  - WiFi Access Point (which is placed at the center of the home)
 *  - UPS [2] (one for Server only, one for external devices)
 *  - Audio Amplifiers (2 channels each) [3]
 *  - Integrated Audio in interface (supports Dolby and multi-channel output thanks to ALSA hacking)
 *  - X10 Controller from Marmitek (CM11 RS232)
 *  - DSL Modem (using PPPoE)
 *  - 56K Modem (RS232, used as answering machine)
 *  - WindowsMobile smart phone (RNDIS over USB)
 *
 * Server and almost all devices are on two different safe power line (during blackout,
 * I'm still able to walk around home watching streaming-movie on my laptop).
 *
 * Server acts also as Firewall (using Shorewall) having the three network
 * (lan, wlan, internet) on different hardware interfaces, with custom policies.
 *
 * I installed a lot of X10 devices, most rooms are equipped with motion and light
 * sensors and their lights/appliance may be controlled locally and remotely.
 *
 * There are some motion sensors out of the house and garage.
 *
 * The garden irrigation is being automated within a month.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_using_shell WOSH Shell and Sessions
 *
 *
 *
 *
 *

There are many ways to interact with WOSH system directly, even if the user will often
act through a specific high-level interface (such as KiosK or other applications).

Sessions

wosh::communication::SessionProtocolDefault


When running \ref page_applications_woshsrv "WOSH Server" a \c stdin/stdout shell is activated
by default, it is very similar to POSIX shell and it allows the user to browse the system,
execute commands and read results. Since logs are prompted on \c stderr by default, it may 
be flodded even while you typing (but they won't interfere each other).
This specific wosh::Session is implemented by wosh::communication::SessionShell.

GUI software as \ref page_applications_woshshop "WOSH WorkShop" supports multiple
independent consoles (just like GUI desktops of common operative systems).
-----------IMAGE

Finally, user may interact with WOSH remotely, through any \c CommunicationService.
My favorite communicator is wosh::devices::JabberGlooxBundle, it act as a bot for
\c jabber network (such as \b GTalk) and once configured it will appear just an human friend
in the contact list. I may send messages to any WOSH users (see \ref page_using_communication),
but even interact just as the Shell described before.
wosh::services::CommunicationManagerBundle is required in order to initialize and route messages
to wosh::communication::SessionIM handler.
-----------IMAGE




 * . is a low-level service
 * which lets users access to the system (run Methods, get and set Properties).
 *
 * It really looks like a POSIX terminal and basic commands are very similar too. 
 *
 * Since WOSH is still in development state, I usually run it in a remote shell and
 * start a local shell from/to standard input/output (just like a Linux terminal or Windows' prompt).
 *
 * Input is parsed by wosh::session::SessionProtocolShell, which will also render the
 * response and interacts with a wosh::session::Session implementation.
 *
 * Session Server is a very important component because it manages also IM (Instant Messaging)
 * sessions.
 * When users want to interact 'directly' with WOSH, then Session Server is the proxy.
 * (such a direct shell command from an SMS or a GMail/GTalk message).
 *
 * A sample flow is:
 *  - User send a command to the Session Server (from stdin or through a generic WOSH Communicator)
 *  - the command is parsed and a wosh::Request message is generated and posted on the (current bus),
 *    destination URI is current path.
 *  - Session parses the wosh::Response message and convert in a standard human-readable text.
 *  - output is redirected to the user (on stdout or through a generic WOSH Communicator)
 *
 * Here is prompted I/O of some basic commands (<a href="../../var/log/sample.Shell.log">/var/log/sample.Shell.log</a>):
 * \include /var/log/sample.Shell.log
 *
 *
 * There are also some advanced features (like regex Destination with expressions)
 *  which are inherited by the WOSH Framework functionalities, you may give a look to
 * <a href="../../var/log/sample.Shell.advanced.log">/var/log/sample.Shell.advanced.log</a>
 *
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_using_multimedia Multimedia
 *
 * \note
 *  Video is under planning, WOSH actually supports Audio Multimedia.
 *
 * Almost all rooms have been equipped with an audio box, because of architecture and rack position
 * it was simpler to place (in-wall) wires and have amplifiers in the rack. Each channel (box) is
 * hardware-independent: from the input (audio) line (by the audio-box point of view) through
 * the amplifier and finally the audio box.
 *
 * My server-hardware comes with a built-in Intel Audio card (Dolby surround), I'm using ALSA and
 * hacking its configuration I was able to have SIX (good) independent channel as (virtual) devices.
 *
 * So, I can play a different song in each room, or same song with different volumes and so on.
 *
 * WOSH server runs an instance of wosh::devices::PlayerGStreamerBundle for each channel (virtual device)
 * and some more mixed channels (both bathrooms, kitchen and living room together, the whole house).
 *
 * Moreover the workstation (and laptop) runs \ref page_applications_woshremote "WOSH Remote"
 * or \ref page_applications_woshshop "WOSH WorkShop" and they support a custom (Qt-phonon based)
 * wosh::interfaces::devices::PlayerAudio implementation: wosh::devices::PlayerPhonon
 * 
 * Here is prompted I/O of some basic commands of PlayerAudio devices (using PlayerGStreamer)
 * (<a href="../../var/log/sample.Multimedia.Audio.log">/var/log/sample.Multimedia.Audio.log</a>):
 * \include /var/log/sample.Multimedia.Audio.log
 *
 * A management service in the Multimedia context is wosh::services::MediaDirectorBundle, which takes care
 * of the whole house-multimedia and is aware of the distributed status, relations within multimedia
 * renderers.
 *
 * One (or more) multimedia device (such as audio box) is linked to a MediaZone which is mapped to 
 * its location (such as home/ground_floor/living_room), it also holds many other settings.
 * Media Director manages MediaZone(s), their setup, update and invocation.
 *
 * The other (optional) key feature of Media Director is to keep track of playing media for each 
 * MediaZone (and user), SQL support and MySQL server are required. The database will be updated
 * on each playback, so Media Director is able to restore last scenario or guess one.
 *
 * Media Director simplifies the 'multimedia mobility' and supports smart shortcuts about entertainment.
 *
 *
 * \warning Specifications and Implementation of Media Director is under planning/development.
 *
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_using_communication Communication
 *
 * Communication and remote control is a must within Smart home (automation).
 *
 * \warning The current architecture and specification are not finalized yet. (but nearly to be)
 * 
 * As you may have read in \ref page_specifications, WOSH is a message-based system, so the
 * request => response pattern is deeply integrated into implementation.
 * By humans' point of view we still act as another actor in the scene:
 * making requests and parsing responses, as usual the process is (full) asynchronous.
 *
 * There are usually many communication channels, each one has different (technologic) features
 * and each (target) user may prefer a custom communicator anytime.
 *
 * Let's consider following use-cases:
 *  - the Alarm system want to notify user(s) of current status
 *  - an user want to communicate with another
 *  - an user want to interact remotely with WOSH (send and receive)
 *
 * So, there are some fundamental points:
 *  - we need a centralized system which select the Communicator (channel) to be used
 *    for each transaction (message/user)
 *  - the manager will need some information to make a good selection:
 *     - available communicators and their status
 *     - relations between communicators and users' location
 *     - last used communicators
 *
 * The centralized service is wosh::services::CommunicationManagerBundle and it is
 * a smart router of messages, this type of messages is based on wosh::Notification.
 *
 * There are many services which works as adapters/bridges, implementing the interface
 * wosh::interfaces::services::CommunicatorService:
 *
 *  - Jabber (GTalk) Bot [wosh::devices::JabberGlooxBundle]
 *  - Windows Mobile SMS [wosh::devices::WindowsMobileBundle]
 *  - Mail POP3/SMTP [wosh::devices::MailBoxBundle]
 *  - Desktop Notifier [wosh::services::DesktopNotifierBundle]
 *
 *  - MediaDirector [wosh::services::MediaDirectorBundle]
 *
 * By user's point of view it's still a configuration task.
 * You just need to configure the services.
 *
 * 
 * Shell protocol provides an useful command for sending a notification: \c "notify <USER> <MESSAGE>"
 *
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_using_devices Devices
 *
 * An home automation system without Devices is quite useless, WOSH framework defines
 * an abstraction layer (using interfaces) to standardize the features of each (real) device.
 *
 *
 * wosh::devices::ModemDslBundle is a device-bundle which provides real-time stats,
 * online status of the xDSL connection and notifies disconnection.
 * It is supported on POSIX system only and it is based on \c pppstatus program (part of PPPoE driver)
 *
 * wosh::devices::PlayerGStreamer is another device-bundle, implementing the PlayerAudio interface.
 *
 * My house is (mostly) X10 embedded, I installed many sensors and switches.
 * As you may know X10 is an old protocol which communicate over the power-line without
 * any extra (custom) cable.
 * The X10 controller is connected (RS232/USB) to the Residential gateway which runs
 * Heyu and WOSH Server. Heyu is an open source software which manages the X10 protocol
 * and has been chosen as lower layer of WOSH adapter (wosh::services::HeyuBundle)
 *
 * Here is prompted I/O of some basic commands of X10 devices (using HeyuBundle)
 * (<a href="../../var/log/sample.Devices.X10.log">/var/log/sample.Devices.X10.log</a>):
 * \include /var/log/sample.Devices.X10.log
 *
 *
 * Devices usually raise events (wosh::Fact) to inform the whole (distributed) system,
 * these messages are broadcasted on bus \b wosh.Bus.Device (they don't want to flood the core bus)
 *
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_using_building Building and Appliances
 *
 * But devices are still 'low-level', very hardware and software dependent and they are a lot.
 *
 * An higher level approach is often required for automations and cooperation of services.
 * The whole house is represented with wosh::BuildingObject implementations' as Floor(s), Room(s), Appliance(s), ..
 *
 * Here is prompted I/O of some basic commands of building objects (using BuildingManagerBundle)
 * (<a href="../../var/log/sample.Building.log">/var/log/sample.Building.log</a>):
 * \include /var/log/sample.Building.log
 *
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_using_automations Automations
 * 
 * Smart home, is simplified as 'Home Automation', sounds like automations are really required..
 * Personally, i think it's still true until a decent Neural-net or Rule engine comes.
 *
 * While waiting.. we have AutomationManagerBundle service, it hosts Automations (and its implementations)
 * and manages their lifecycle.
 *
 * Let's see a real world example: my X10 switch and dimmer can control the play/stop and volume of the
 * box (play list) of the room (kitchen).
 * 
 * \verbatim
root@wosh1:Devices# fake_event E6 StateChanged INT(100)
D^13:34:36    AutomationManager: : Executing 'music_controller' [MsgID=229557695]
D^13:34:37    PlayerCucina::busMessage() : Executing 'next
\endverbatim
 *
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_using_networking Networking
 *
 * \note
 *  Networking is not required or necessary, you may test or use on a single host.
 *
 * Networking is an huge task, especially for network distributed systems.
 *
 * WOSH Framework tries to be as transparent (but scalable) as possible,
 * for technical information or issues you should read \ref page_core_network
 * and page_framework_network pages.
 *
 * This section is a little how-to for users and developers which don't care about
 * WOSH networking.
 *
 * You will be happy to hear that when everything goes right, WOSH Networking is
 * incredibly easy. Basically you will need to configure the system once and nothing more.
 *
 * But there are at least some requirements such as:
 *
 *  - You have a minimal knowledge about networking.
 *
 *  - Network must already work fine, in other words: a generic application must be
 *    able to connect to other (target) machines in the network on selected ports.
 *    When a firewall is active, it must be configured properly.
 *
 *  - WOSH networking is actually based on UDP and TCP protocols.
 *
 *  - WOSH network is \b NOT providing any security. You system/network configuration
 *    must provide the security! (this means that WOSH is actually hackable as any
 *    other application/user/host, moreover it is conceptually a security hole when
 *    the network is not well-designed)
 *
 * After that, let's see how to run/configure WOSH networking, first step is Discovery.
 *
 * WOSH hosts must be able to see each other in other to communicate.
 * This job is performed by wosh::services::DiscoveryBundle service using UDP protocol.
 *
 * You just need to configure the broadcast address for your network and sometimes the 
 * binding address (Discovery service is able to listed on all network interfaces).
 * A sample configuration file of \c Discovery service is available
 * <a href="../../etc/wosh/bundles-available/001_Discovery.conf">001_Discovery.conf</a>
 *
 * In the sample, host listens on all available network interfaces and send the Discovery
 * packet to 192.168.0.255 at port 8787 and to 169.254.2.255 at port 8787.
 *
 * Just few points about that for newbie:
 *  - Port (8787) must be the same for all hosts (but you can change)
 *  - Don't change the binding address-port (0.0.0.0:8787) if you don't know what you are doing
 *  - Change the broadcast address according to your LAN/WLAN network (or both).
 *    Most routers and POSIX system set the Local LAN to 192.168.0.x where x is an host
 *    in the network. Check out some networking tutorial over the Internet if this
 *    information is new for you.
 *
 *
 * Once two hosts are aware of each other presence, a connection may be established.
 * This document doesn't really care about how this is done, but how get it working.
 * The most important configuration keys are defined in the NetworkManager group of
 * \c /etc/wosh/wosh.conf file:
 * \verbatim
AutoLoadProtocols=wosh::network::NetworkProtocolTcp
ListenChannels=TCP://192.168.0.28:9595
\endverbatim
 *
 * You will need to configure the \c ListenChannels key for your network. This is the 
 * binding address-port of the TCP socket. Just set it to the IP of current host.
 *
 * If the network and the configuration are correct, (and keeping default settings)
 * WOSH will auto-connect to new hosts and channel will be automatically managed
 * by the Network Manager module.
 *
 * \note
 *  You may see some warning messages in the Log files, but the system is actually working nice.
 *
 *
 * As you may have seen in the sample log file, there are some very important
 * properties stored in wosh::WoshHost object (response of \c props command):
 * \verbatim
  wosh28:Network/Hosts/wosh28 :: Properties:
                 Name                                                Value
--------------------------------------------------------------------------
                 name                                                wosh1
                 type                                       wosh::WoshHost
                 Seen                                  2009-12-19 06:19:55
       DiscoverSource                                     192.168.0.1:8787
 DiscoveryBindAddress                                         0.0.0.0:8787
      NotifyFrequency                                                   60
      ProtocolVersion                                                    0
          KernelState                                                    1
           KernelType                                                    0
        ProtocolCount                                                    1
      ConnectionCount                                                    2
            Protocols                              TCP://192.168.0.1:9595;
          Connections TCP://192.168.0.1{1042291111};TCP://192.168.0.28{0};
\endverbatim
 *
 * Here is prompted I/O of some basic commands of wosh::NetworkManager core-service
 * (<a href="../../var/log/sample.Network.shell.log">/var/log/sample.Network.shell.log</a>):
 * \include /var/log/sample.Network.shell.log
 *
 *
 *
 ****************************************************************************
 *
 */ 

